CCI API Reference¶

The cci_bind_param function binds data in the bind variable of prepared statement. This function converts value of the given a_type to an actual binding type and stores it. Subsequently, whenever cci_execute() is called, the stored data is sent to the server. If cci_bind_param () is called multiple times for the same index, the latest configured value is valid.

To bind NULL to the database, choose one of below settings.

• Set the value of value to a NULL pointer
• Set the value of u_type to CCI_U_TYPE_NULL

The following shows a part of code to bind NULL.

res = cci_bind_param (req, 2 /* binding index*/, CCI_A_TYPE_STR, NULL, CCI_U_TYPE_STRING, CCI_BIND_PTR);

or

res = cci_bind_param (req, 2 /* binding index*/, CCI_A_TYPE_STR, data, CCI_U_TYPE_NULL, CCI_BIND_PTR);

can be used.

If CCI_BIND_PTR is configured for flag, the pointer of value variable is copied (shallow copy), but no value is copied. If it is not configured for flag, the value of value variable is copied (deep copy) by allocating memory. If multiple columns are bound by using the same memory buffer, CCI_BIND_PTR must not be configured for the flag.

T_CCI_A_TYPE is a C language type that is used in CCI applications for data binding, and consists of primitive types such as int and float, and user-defined types defined by CCI such as T_CCI_BIT and T_CCI_DATE. The identifier for each type is defined as shown in the table below.

T_CCI_U_TYPE is a column type of database and data bound though the value argument is converted into this type. The cci_bind_param () function uses two kinds of types to send information which is used to convert U-type data from A-type data; the U-type data can be interpreted by database language and the A-type data can be interpreted by C language.

There are various A-type data that are allowed by U-type data. For example, CCI_U_TYPE_INT can receive CCI_A_TYPE_STR as A-type data including CCI_A_TYPE_INT. For information on type conversion, see Implicit Type Conversion.

Both T_CCI_A_TYPE and T_CCI_U_TYPE enum(s) are defined in the cas_cci.h file. The definition of each identifier is described in the table below.

When the string including the date is used as an input parameter of DATE, DATETIME, or TIMESTAMP, "YYYY/MM/DD" or "YYYY-MM-DD" is allowed for the date string type. Therefore, "2012/01/31" or "2012-01-31" is valid, but "01/31/2012" is invalid. The following is an example of having the string that includes the date as an input parameter of the date type.

// "CREATE TABLE tbl(aa date, bb datetime)";

char *values[][3] =
{
    {"1994/11/30", "1994/11/30 20:08:08"},
    {"2008-10-31", "2008-10-31 20:08:08"}
};

req = cci_prepare(conn, "insert into tbl (aa, bb) values ( ?, ?)", CCI_PREPARE_INCLUDE_OID, &error);

for(i=0; i< 2; i++)
{
    res = cci_bind_param(req, 1, CCI_A_TYPE_STR, values[i][0], CCI_U_TYPE_DATE, (char)NULL);
    res = cci_bind_param(req, 2, CCI_A_TYPE_STR, values[i][1], CCI_U_TYPE_DATETIME, (char)NULL);
    cci_execute(req, CCI_EXEC_QUERY_ALL, 0, err_buf);
}

The cci_bind_param_array function binds a parameter array for a prepared cci_execute_array() is called, data is sent to the server by the stored value pointer. If cci_bind_param_array () is called multiple times for the same index, the last configured value is valid. If NULL is bound to the data, a non-zero value is configured in null_ind. If value is a NULL pointer, or u_type is CCI_U_TYPE_NULL, all data are bound to NULL and the data buffer used by value cannot be reused. For the data type of value for a_type, see the cci_bind_param() function description.

The cci_bind_param_array_size function determines the size of the array to be used in cci_bind_param_array(). cci_bind_param_array_size () must be called first before cci_bind_param_array() is used.

The cci_bind_param_ex function works as the same with cci_bind_param(). However, it has an additional argument, length, which specifies the byte length of a string if bound data is a string.

The length argument can be used for binding a string which includes '\0' as below.

cci_bind_param_ex(statement, 1, CCI_A_TYPE_STR, "aaa\0bbb", 7, CCI_U_TYPE_STRING, 0);

The cci_blob_free function frees memory of blob struct.

The cci_blob_new function creates an empty file where LOB data is stored and returns locator referring to the data to blob struct.

The cci_blob_read function reads as much as data from start_pos to length of the LOB data file specified in blob; then it stores it in buf and returns it.

The cci_blob_size function returns data file size that is specified in blob.

The cci_blob_write function reads as much as data from buf to length and stores it from start_pos of the LOB data file specified in blob.

Cancel the running query on the other thread. This function executes the same behavior as Statement.cancel() method in JAVA.

The following shows how to cancel the query execution of a thread.

/* gcc -o pthr pthr.c -m64 -I${CUBRID}/include -lnsl ${CUBRID}/lib/libcascci.so -lpthread
*/


#include <stdio.h>
#include <cas_cci.h>
#include <unistd.h>
#include <pthread.h>
#include <string.h>
#include <time.h>

#define QUERY "select * from db_class A, db_class B, db_class C, db_class D, db_class E"

static void *thread_main (void *arg);
static void *execute_statement (int con, char *sql_stmt);

int
main (int argc, char *argv[])
{
    int thr_id = 0, conn_handle = 0, res = 0;
    void *jret;
    pthread_t th;
    char url[1024];
    T_CCI_ERROR error;
    snprintf (url, 1024, "cci:CUBRID:localhost:33000:demodb:PUBLIC::");

    conn_handle = cci_connect_with_url_ex (url, NULL, NULL, &error);

    if (conn_handle < 0)
    {
        printf ("ERROR: %s\n", error.err_msg);
        return -1;
    }

    res = pthread_create (&th, NULL, &thread_main, (void *) &conn_handle);

    if (res < 0)
    {
        printf ("thread fork failed.\n");
        return -1;
    }
    else
    {
        printf ("thread started\n");
    }
    sleep (5);
    // If thread_main is still running, below cancels the query of thread_main.
    res = cci_cancel (conn_handle);
    if (res < 0)
    {
        printf ("cci_cancel failed\n");
        return -1;
    }
    else
    {
        printf ("The query was canceled by cci_cancel.\n");
    }
    res = pthread_join (th, &jret);
    if (res < 0)
    {
        printf ("thread join failed.\n");
        return -1;
    }

    printf ("thread_main was cancelled with\n\t%s\n", (char *) jret);
    free (jret);

    res = cci_disconnect (conn_handle, &error);
    if (res < 0)
    {
        printf ("ERROR: %s\n", error.err_msg);
      return res;
    }

    return 0;
}

void *
thread_main (void *arg)
{
    int con = *((int *) arg);
    int ret_val;
    void *ret_ptr;
    T_CCI_ERROR error;

    cci_set_autocommit (con, CCI_AUTOCOMMIT_TRUE);
    ret_ptr = execute_statement (con, QUERY);
    return ret_ptr;
}

static void *
execute_statement (int con, char *sql_stmt)
{
    int col_count = 1, ind, i, req;
    T_CCI_ERROR error;
    char *buffer;
    char *error_msg;
    int res = 0;

    error_msg = (char *) malloc (128);
    if ((req = cci_prepare (con, sql_stmt, 0, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_prepare ERROR: %s\n", error.err_msg);
        goto conn_err;
    }

    if ((res = cci_execute (req, 0, 0, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_execute ERROR: %s\n", error.err_msg);
        goto execute_error;
    }

    if (res >= 0)
    {
        while (1)
        {
            res = cci_cursor (req, 1, CCI_CURSOR_CURRENT, &error);
            if (res == CCI_ER_NO_MORE_DATA)
            {
                break;
            }
            if (res < 0)
            {
                snprintf (error_msg, 128, "cci_cursor ERROR: %s\n",
                    error.err_msg);
                return error_msg;
            }

            if ((res = cci_fetch (req, &error)) < 0)
            {
                snprintf (error_msg, 128, "cci_fetch ERROR: %s\n",
                    error.err_msg);
                return error_msg;
            }

            for (i = 1; i <= col_count; i++)
            {
                if ((res = cci_get_data (req, i, CCI_A_TYPE_STR, &buffer, &ind)) < 0)
                {
                    snprintf (error_msg, 128, "cci_get_data ERROR\n");
                    return error_msg;
                }
            }
        }
    }

    if ((res = cci_close_query_result (req, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_close_query_result ERROR: %s\n", error.err_msg);
        return error_msg;
    }
execute_error:
    if ((res = cci_close_req_handle (req)) < 0)
    {
        snprintf (error_msg, 128, "cci_close_req_handle ERROR\n");
    }
conn_err:
    return error_msg;
}

The cci_clob_free function frees memory of CLOB struct.

The cci_clob_new function creates an empty file where LOB data is stored and returns locator referring to the data to clob struct.

The cci_clob_read function reads as much as data from start_pos to length in the LOB data file specified in clob; then it stores it in buf and returns it.

The cci_clob_size function returns data file size that is specified in clob.

The cci_clob_write function reads as much as data from buf to length and then stores the value from start_pos in LOB data file specified in clob.

The cci_close_query_result funciton closes the resultset returned by cci_execute(), cci_execute_array() or cci_execute_batch(). If you run cci_prepare() repeatedly without closing the request handle(req_handle), it is recommended to call this function before calling cci_close_req_handle().

The cci_close_req_handle function closes the request handle obtained by cci_prepare().

The cci_col_get function gets an attribute value of collection type. If the name of the class is C, and the domain of set_attr is set (multiset, sequence), the query looks like as follows:

SELECT a FROM C, TABLE(set_attr) AS t(a) WHERE C = oid;

That is, the number of members becomes the number of records.

The cci_col_seq_drop function drops the index-th (base: 1) member of the sequence attribute values. The following example shows how to drop the first member of the sequence attribute values.

cci_col_seq_drop(conn_handle, oid_str, seq_attr, 1, err_buf);

The cci_col_seq_insert function inserts one member at the index-th (base: 1) position of the sequence attribute values. The following example shows how to insert "a" at the first position of the sequence attribute values.

cci_col_seq_insert(conn_handle, oid_str, seq_attr, 1, "a", err_buf);

The cci_col_seq_put function replaces the index-th (base: 1) member of the sequence attribute values with a new value. The following example shows how to replace the first member of the sequence attributes values with "a".

cci_col_seq_put(conn_handle, oid_str, seq_attr, 1, "a", err_buf);

The cci_col_set_add function adds one member to the set attribute values. The following example shows how to add "a" to the set attribute values.

cci_col_set_add(conn_handle, oid_str, set_attr, "a", err_buf);

The cci_col_set_drop function drops one member from the set attribute values. The following example shows how to drop "a" from the set attribute values.

cci_col_set_drop(conn_handle, oid_str, set_attr, "a", err_buf);

The cci_col_size function gets the size of the set (seq) attribute.

A connection handle to the database server is assigned and it tries to connect to the server. If it has succeeded, the connection handle ID is returned; if fails, an error code is returned.

The cci_connect_ex function returns CCI_ER_DBMS error and checks the error details in the database error buffer (err_buf) at the same time. In that point, it is different from cci_connect() and the others are the same as the cci_connect() function.

The cci_connect_with_url function connects a database by using connection information passed with a url argument. If broker's HA feature is used in CCI, you must specify the connection information of the standby broker server with altHosts property, which is used for the failover, in the url argument of this function. It returns the ID of a connection handle on success; it returns an error code on failure. For details about HA features of broker, see Duplexing Brokers.

<url> ::= cci:CUBRID:<host>:<port>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]
<property> ::= altHosts=<alternative_hosts> [ &rcTime=<time>] [ &loadBalance=true|false]
             |{login_timeout|loginTimeout}=<milli_sec>
             |{query_timeout|queryTimeout}=<milli_sec>
             |{disconnect_on_query_timeout|disconnectOnQueryTimeout}=true|false
             | logFile=<file_name>
             | logBaseDir=<dir_name>
             | logSlowQueries=true|false[&slowQueryThresholdMillis=<milli_sec>]
             | logTraceApi=true|false
             | logTraceNetwork=true|false

<alternative_hosts> ::= <host>:<port> [,<host>:<port>]

<host> := HOSTNAME | IP_ADDR
<time> := SECOND
<milli_sec> := MILLI SECOND

altHosts is the property related to connection target and loginTimeout, queryTimeout, and disconnectOnQueryTimeout are the properties related to timeout; logSlowQueries, logTraceApi, and logTraceNetwork are the properties related to log information configuration for debugging. Note that a property name which is a value to be entered in the url argument is not case sensitive.

• host: A host name or IP address of the master database

• port: A port number

• db_name: A name of the database

• db_user: A name of the database user

• db_password: A database user password

• altHosts = standby_broker1_host, standby_broker2_host, ...: Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts.

  Note

  Even if there are RW and RO together in ACCESS_MODE* setting of brokers of main host and altHosts, application decides the target host to access without the relation for the setting of ACCESS_MODE. Therefore, you should define the main host and altHosts as considering ACCESS_MODE of target brokers.

• rcTime: After the failure occurred on the first connected broker, the application connects to the broker specified by altHosts(broker failover). Then it attempts to reconnect to the first connected broker at every rcTime(default value: 600 seconds).

• loadBalance: When this value is true, the applications try to connect to the main host and alternative hosts specified with the altHosts property as a random order. (default value: false).

• login_timeout | loginTimeout: Timeout value (unit: msec.) for database login. Upon timeout, a CCI_ER_LOGIN_TIMEOUT (-38) error is returned. The default value is 30,000(30 sec.). If this value is 0, it means infinite waiting. This value is also applied when internal reconnection occurs after the initial connection.

• query_timeout | queryTimeout: If time specified in these properties has expired when calling cci_prepare(), cci_execute(), etc. a cancellation message for query request which was sent to a server will be delivered and called function returns a CCI_ER_QUERY_TIMEOUT (-39) error. The value returned upon timeout may vary depending on a value specified in disconnect_on_query_timeout. For details, see disconnect_on_query_timeout.

  Note

  If you use cci_execute_batch() or cci_execute_array()function, or set CCI_EXEC_QUERY_ALL in cci_execute() function to run multiple queries at once, query timeout is applied to one function, not to one query. In other words, if query timeout occurs after the start of a function, a function running is quit.

• disconnect_on_query_timeout | disconnectOnQueryTimeout: Whether to disconnect socket immediately after time for query request has expired. It determines whether to terminate a socket connection immediately or wait for server response after sending cancellation message for query request to a server when calling cci_prepare(), cci_execute(), etc. The default value is false, meaning that it will wait for server response. It this value is true, a socket will be closed immediately after sending a cancellation message to a server upon timeout and returns the CCI_ER_QUERY_TIMEOUT (-39) error. (If an error occurs on database server side, not on broker side, it returns -1. If you want to view error details, see error codes in "database error buffer." You can get information how to check error codes in CCI Error Codes and Error Messages.) Please note that there is a possibility that a database server does not get a cancellation message and execute a query even after an error is returned.

• logFile: A log file name for debugging (default value: cci_ <handle_id> .log). <handle_id> indicates the ID of a connection handle returned by this function.

• logBaseDir: A directory where a debug log file is created. The file name including the path will be logBaseDir/logFile, and the relative path is possible.

• logSlowQueries: Whether to log slow query for debugging (default value: false)

• slowQueryThresholdMillis: Timeout for slow query logging if slow query logging is enabled (default value: 60000, unit: milliseconds)

• logTraceApi: Whether to log the start and end of CCI functions

• logTraceNetwork: Whether to log network data content transferred of CCI functions

Example

--connection URL string when a property(altHosts) is specified for HA
URL=cci:CUBRID:192.168.0.1:33000:demodb:::?altHosts=192.168.0.2:33000,192.168.0.3:33000

--connection URL string when properties(altHosts,rcTime) is specified for HA
URL=cci:CUBRID:192.168.0.1:33000:demodb:::?altHosts=192.168.0.2:33000,192.168.0.3:33000&rcTime=600

--connection URL string when properties(logSlowQueries,slowQueryThresholdMills, logTraceApi, logTraceNetwork) are specified for interface debugging
URL = "cci:cubrid:192.168.0.1:33000:demodb:::?logSlowQueries=true&slowQueryThresholdMillis=1000&logTraceApi=true&logTraceNetwork=true"

The cci_connect_with_url_ex function returns CCI_ER_DBMS error and checks the error details in the database error buffer (err_buf) at the same time. In that point, it is different from cci_connect_with_url() and the others are the same as the cci_connect_with_url() function.

The cci_cursor function moves the cursor specified in the request handle to access the specific record in the query result executed by cci_execute(). The position of cursor is moved by the values specified in the origin and offset values. If the position to be moved is not valid, CCI_ER_NO_MORE_DATA is returned.

Example

//the cursor moves to the first record
cci_cursor(req, 1, CCI_CURSOR_FIRST, &err_buf);

//the cursor moves to the next record
cci_cursor(req, 1, CCI_CURSOR_CURRENT, &err_buf);

//the cursor moves to the last record
cci_cursor(req, 1, CCI_CURSOR_LAST, &err_buf);

//the cursor moves to the previous record
cci_cursor(req, -1, CCI_CURSOR_CURRENT, &err_buf);

The cci_cursor_update function updates cursor_pos from the value of the index -th column to value. If the database is updated to NULL, value becomes NULL. For update conditions, see cci_prepare(). The data types of value for a_type are shown in the table below.

Data types of value for a_type are as below.

The cci_datasource_borrow function obtains CCI connection to be used in T_CCI_DATASOURCE struct.

A property name of a DATASOURCE is specified in key, a value in val. The changed property value by this function is applied to all connections in the datasource.

The following shows names and values of changeable properties.

Example

...
ps = cci_property_create ();
...
ds = cci_datasource_create (ps, &err);
...
cci_datasource_change_property(ds, "login_timeout", "5000");
cci_datasource_change_property(ds, "default_lock_timeout", "2000");
cci_datasource_change_property(ds, "default_isolation", "TRAN_REP_CLASS_COMMIT_INSTANCE");
cci_datasource_change_property(ds, "default_autocommit", "true");
...

The cci_datasource_create function creates DATASOURCE of CCI.

The cci_datasource_destroy function destroys DATASOURCE of CCI.

The cci_datasource_release function returns CCI connection released in T_CCI_DATASOURCE struct. If you want to reuse the connection after calling this function, recall cci_datasource_borrow().

The cci_disconnect function disconnects all request handles created for conn_handle. If a transaction is being performed, the handles are disconnected after cci_end_tran() is executed.

The cci_end_tran function performs commit or rollback on the current transaction. At this point, all open request handles are terminated and the connection to the database server is disabled. However, even after the connection to the server is disabled, the connection handle remains valid.

You can configure the default value of auto-commit mode by using CCI_DEFAULT_AUTOCOMMIT broker parameter upon startup of an application. If configuration on broker parameter is omitted, the default value is ON; use the cci_set_autocommit() function to change auto-commit mode within an application. If auto-commit mode is OFF, you must explicitly commit or roll back transaction by using the cci_end_tran() function.

Converts the input string to a string that can be used in the CUBRID query. The following parameters are specified in this function: connection handle or no_backslash_escapes setting value, output string pointer, input string pointer, the length of the input string, and the address of the T_CCI_ERROR struct variable.

When the system parameter no_backslash_escapes is yes (default) or when the CCI_NO_BACKSLASH_ESCAPES_TRUE value is sent to the connection handle location, the string is converted to the following characters.

• ' (single quote) => ' + ' (escaped single quote)

When the system parameter no_backslash_escapes is no or when the CCI_NO_BACKSLASH_ESCAPES_FALSE value is sent to the connection handle location, the string is converted to the following characters:

• \n (new line character, ASCII 10) => \ + n (backslash + Alphabet n)
• \r (carriage return, ASCII 13) => \ + r (backslash + Alphabet r)
• \0 (ASCII 0) => \ + 0 (backslash + 0(ASCII 48)
• \ (backslash) => \ + \

You can assign the space where the result string will be saved by using the length parameter. It will take as much as the byte length of the maximum input string * 2 + 1.

The cci_execute function executes the SQL statement (prepared statement) that has executed cci_prepare(). A request handle, flag, the maximum length of a column to be fetched, and the address of a T_CCI_ERROR construct variable in which error information being stored are specified as arguments.

Through a flag, the way of query execution can be set as all queries or the first one.

If the flag is set to CCI_EXEC_QUERY_ALL, all prepared queries(separated by semicolon) are executed. If not, only the first query is executed.

If the flag is set to CCI_EXEC_QUERY_ALL, the following rules are applied.

• The return value is the result of the first query.
• If an error occurs in any query, the execution is processed as a failure.
• For a query composed of in a query composed of q1; q2; q3, even if an error occurs in q2 after q1 succeeds the execution, the result of q1 remains valid. That is, the previous successful query executions are not rolled back when an error occurs.
• If a query is executed successfully, the result of the second query can be obtained using cci_next_result().

max_col_size is a value that is used to determine the maximum length of a column to be sent to a client when the columns of the prepared statement are CHAR, VARCHAR, BIT or VARBIT. If this value is 0, full length is fetched.

If more than one value is bound to the prepared statement, this gets the values of the variables to be bound and executes the query by binding each value to the variable.

To bind the data, call the cci_bind_param_array_size() function to specify the size of the array, bind each value to the variable by using the cci_bind_param_array() function, and execute the query by calling the cci_execute_array() function. The query result will be stored on the array of T_CCI_QUERY_RESULT structure.

cci_execute_array() function returns the results of queries to the query_result variable. You can use below macros to get the result of each query. In the macro, note that the validation check for each parameter entered is not performed.

After using the query_result variable, you must delete the query_result by using the cci_query_result_free() function.

If autocommit mode is on, each query in the array is committed after executing.

char *query =
    "update participant set gold = ? where host_year = ? and nation_code = 'KOR'";
int gold[2];
char *host_year[2];
int null_ind[2];
T_CCI_QUERY_RESULT *result;
int n_executed;
...

req = cci_prepare (con, query, 0, &cci_error);
if (req < 0)
{
    printf ("prepare error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}

gold[0] = 20;
host_year[0] = "2004";

gold[1] = 15;
host_year[1] = "2008";

null_ind[0] = null_ind[1] = 0;
error = cci_bind_param_array_size (req, 2);
if (error < 0)
{
    printf ("bind_param_array_size error: %d\n", error);
    goto handle_error;
}

error =
    cci_bind_param_array (req, 1, CCI_A_TYPE_INT, gold, null_ind, CCI_U_TYPE_INT);
if (error < 0)
{
    printf ("bind_param_array error: %d\n", error);
    goto handle_error;
}
error =
    cci_bind_param_array (req, 2, CCI_A_TYPE_STR, host_year, null_ind, CCI_U_TYPE_INT);
if (error < 0)
{
    printf ("bind_param_array error: %d\n", error);
    goto handle_error;
}

n_executed = cci_execute_array (req, &result, &cci_error);
if (n_executed < 0)
{
    printf ("execute error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}
for (i = 1; i <= n_executed; i++)
{
    printf ("query %d\n", i);
    printf ("result count = %d\n", CCI_QUERY_RESULT_RESULT (result, i));
    printf ("error message = %s\n", CCI_QUERY_RESULT_ERR_MSG (result, i));
    printf ("statement type = %d\n",
            CCI_QUERY_RESULT_STMT_TYPE (result, i));
}
error = cci_query_result_free (result, n_executed);
if (error < 0)
{
    printf ("query_result_free: %d\n", error);
    goto handle_error;
}
error = cci_end_tran(con, CCI_TRAN_COMMIT, &cci_error);
if (error < 0)
{
    printf ("end_tran: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}

In CCI, multiple jobs can be processed simultaneously when using DML queries such as INSERT / UPDATE / DELETE. CCI_QUERY_RESULT_RESULT and cci_execute_batch() functions can be used to execute such batch jobs. Note that prepared statements cannot be used in the cci_execute_batch() function. The query result will be stored on the array of T_CCI_QUERY_RESULT structure.

Executes sql_stmt as many times as num_sql_stmt specified as a parameter and returns the number of queries executed with the query_result variable. You can use CCI_QUERY_RESULT_RESULT, c:macro:CCI_QUERY_RESULT_ERR_NO, CCI_QUERY_RESULT_ERR_MSG and CCI_QUERY_RESULT_STMT_TYPE macros to get the result of each query. Regarding the summary of these macros, see the cci_execute_array() function.

Note that the validity check is not performed for each parameter entered in the macro.

After using the query_result variable, you must delete the query result by using the cci_query_result_free() function.

If autocommit mode is on, each query in the array is committed after executing.

...
char **queries;
T_CCI_QUERY_RESULT *result;
int n_queries, n_executed;
...
count = 3;
queries = (char **) malloc (count * sizeof (char *));
queries[0] =
    "insert into athlete(name, gender, nation_code, event) values('Ji-sung Park', 'M', 'KOR', 'Soccer')";
queries[1] =
    "insert into athlete(name, gender, nation_code, event) values('Joo-young Park', 'M', 'KOR', 'Soccer')";
queries[2] =
    "select * from athlete order by code desc limit 2";

//calling cci_execute_batch()
n_executed = cci_execute_batch (con, count, queries, &result, &cci_error);
if (n_executed < 0)
{
    printf ("execute_batch: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}
printf ("%d statements were executed.\n", n_executed);

for (i = 1; i <= n_executed; i++)
{
    printf ("query %d\n", i);
    printf ("result count = %d\n", CCI_QUERY_RESULT_RESULT (result, i));
    printf ("error message = %s\n", CCI_QUERY_RESULT_ERR_MSG (result, i));
    printf ("statement type = %d\n",
            CCI_QUERY_RESULT_STMT_TYPE (result, i));
}

error = cci_query_result_free (result, n_executed);
if (error < 0)
{
    printf ("query_result_free: %d\n", error);
    goto handle_error;
}
...

The cci_execute_result function stores the execution results (e.g. statement type, result count) performed by cci_execute() to the array of T_CCI_QUERY_RESULT structure. You can use CCI_QUERY_RESULT_RESULT, CCI_QUERY_RESULT_ERR_NO, CCI_QUERY_RESULT_ERR_MSG, CCI_QUERY_RESULT_STMT_TYPE macros to get the results of each query. Regarding the summary of these macros, see the cci_execute_array() function.

Note that the validity check is not performed for each parameter entered in the macro.

The memory of used query results must be released by the cci_query_result_free() function.

...
T_CCI_QUERY_RESULT *qr;
...

cci_execute( ... );
res = cci_execute_result(req_h, &qr, &err_buf);
if (res < 0)
{
    /* error */
}
else
{
    for (i=1 ; i <= res ; i++)
    {
        result_count = CCI_QUERY_RESULT_RESULT(qr, i);
        stmt_type = CCI_QUERY_RESULT_STMT_TYPE(qr, i);
    }
    cci_query_result_free(qr, res);
}
...

The cci_fetch function fetches the query result executed by cci_execute() from the server-side CAS and stores it to the client buffer. The cci_get_data() function can be used to identify the data of a specific column from the fetched query result.

The cci_fetch_buffer_clear function clears the records temporarily stored in the client buffer.

The cci_fetch_sensitive function sends changed values for sensitive column when the SELECT query result is delivered. If the results by req_handle are not sensitive, they are same as the ones by cci_fetch(). The return value of CCI_ER_DELETED_TUPLE means that the given row has been deleted.

sensitive column means the item that can provide updated value in the SELECT list when you re-request the results. For example, if a column is directly used as an item of the SELECT list without aggregation operation, this column can be called a sensitive column.

When you fetch the result again, the sensitive result receive the data from the server, not from the client buffer.

This function is deprecated. Even if it's called, there will be ignored.

The cci_get_autocommit function returns the auto-commit mode currently configured.

The cci_get_bind_num function gets the number of input bindings. If the SQL statement used during preparation is composed of multiple queries, it represents the number of input bindings used in all queries.

Retrieve CAS information which is connected to conn_handle. The string of the below format is returned to the info_buf.

<host>:<port>,<cas id>,<cas process id>

The below is an example.

127.0.0.1:33000,1,12916

Through CAS ID, you can check the SQL log file of this CAS easily.

For details, see Checking SQL Log.

The cci_get_class_num_objs function gets the number of objects of the class_name class and the number of pages being used. If the flag is configured to 1, an approximate value is fetched; if it is configured to 0, an exact value is fetched.

The cci_get_cur_oid function gets OID of the currently fetched records if CCI_INCLUDE_OID is configured in execution. The OID is represented in string for a page, slot, or volume.

The cci_get_data function gets the col_no -th value from the currently fetched result.

The type of the value variable is determined based on the given type argument, and the value or the pointer is copied to the value variable accordingly. For a value to be copied, the memory for the address to be transferred to the value variable must have been previously assigned. Note that if a pointer is copied, a pointer in the application client library is returned, so the value becomes invalid next time the cci_get_data() function is called.

In addition, the pointer returned by the pointer copy must not be freed. However, if the type is CCI_A_TYPE_SET, the memory must be freed by using the cci_set_free() function after using the set because the set is returned after the T_CCI_SET type memory is allocated. The following table shows the summary of type arguments and data types of their corresponding value values.

Remark

• For LOB type, if the cci_get_data() function is called, meta data with the LOB type column (locator) is displayed. To call data of the LOB type column, the cci_blob_read() function should be called.

The below example shows a part of a code to print out the fetched result with cci_get_data().

...

if ((res=cci_get_data(req, i, CCI_A_TYPE_INT, &buffer, &ind))<0) {
    printf( "%s(%d): cci_get_data fail\n", __FILE__, __LINE__);
    goto handle_error;
}
if (ind != -1)
        printf("%d \t|", buffer);
else
        printf("NULL \t|");
...

The cci_get_db_parameter function gets a parameter value specified in the database.

The data type of value for param_name is shown in the table below.

In cci_get_db_parameter() and cci_set_db_parameter(), the input/output unit of CCI_PARAM_LOCK_TIMEOUT is milliseconds.

CCI_PARAM_MAX_STRING_LENGTH is measured in bytes and it gets a value defined in the MAX_STRING_LENGTH broker parameter.

The cci_get_db_version function gets the Database Management System (DBMS) version.

The cci_get_err_msg function stores error messages corresponding to the error code in the error message buffer. For details on error codes and error messages, see CCI Error Codes and Error Messages.

note:: From CUBRID 9.1, CUBRID ensures that all functions which have err_buf parameter store an error value into err_buf parameter, so you don't need to use cci_get_err_msg function if a function has err_buf parameter.

req = cci_prepare (con, query, 0, &err_buf);
if (req < 0)
{
    printf ("error: %d, %s\n", err_buf.err_code, err_buf.err_msg);
    goto handle_error;
}

On the previous version of 9.1, an err_buf value was stored only when CCI_ER_DBMS error occurred. So printing an error message should have been separated by CCI_ER_DBMS error.

req = cci_prepare (con, query, 0, &err_buf);
if (req < 0)
{
    if (req == CCI_ER_DBMS)
    {
        printf ("error: %s\n", err_buf.err_msg);
    }
    else
    {
        char msg_buf[1024];
        cci_get_err_msg(req, msg_buf, 1024);
        printf ("error: %s\n", msg_buf);
    }
    goto handle_error;
}

From 9.1, you can simplify the branch of the above code by using cci_get_error_msg function.

req = cci_prepare (con, query, 0, &err_buf);
if (req < 0)
{
    char msg_buf[1024];
    cci_get_error_msg(req, err_buf, msg_buf, 1024);
    printf ("error: %s\n", msg_buf);
    goto handle_error;
}

Saves the error messages corresponding to the CCI error codes in the message buffer. If the value of CCI error code is CCI_ER_DBMS, the database error buffer (err_buf) receives the error message sent from the data server and saves it in the message buffer(msg_buf). For details on error codes and messages, see CCI Error Codes and Error Messages.

Returns the cursor holdability setting value about the result set from the connection handle. When it is 1, the connection is disconnected or the cursor is holdable until the result set is intentionally closed regardless of commit. When it is 0, the result set is closed when committed and the cursor is not holdable. For more details on cursor holdability, see Cursor Holdability.

Gets the primary key of the INSERT statement which executed at the last time.

#include <stdio.h>
#include "cas_cci.h"

int main ()
{
    int con = 0;
    int req = 0;

    int error;
    T_CCI_ERROR cci_error;


    char *query = "insert into t1 values(NULL);";
    char *value = NULL;

    con = cci_connect ("localhost", 33000, "demodb", "dba", "");

    if (con < 0)
    {
        printf ("con error\n");
        return;
    }

    req = cci_prepare (con, query, 0, &cci_error);
    if (req < 0)
    {
        printf ("cci_prepare error: %d\n", req);
        printf ("cci_error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
        return;
    }
    error = cci_execute (req, 0, 0, &cci_error);
    if (error < 0)
    {
        printf ("cci_execute error: %d\n", error);
        return;
    }

    error = cci_get_last_insert_id (con, &value, &cci_error);
    if (error < 0)
    {
        printf ("cci_get_last_insert_id error: %d\n", error);
        return;
    }

    printf ("## last insert id: %s\n", value);

    error = cci_close_req_handle (req);
    error = cci_disconnect (con, &cci_error);
    return 0;
}

Return login timeout value to timeout.

Saves the query plan to the result buffer; the query plan about the request handle which the cci_prepare function returned.

You can call this function whether to call the cci_execute function or not.

After calling the cci_get_query_plan function, if the use of a result buffer ends, you should call the cci_query_info_free() function to release the result buffer created by cci_get_query_plan function.

char *out_buf;
...
req = cci_prepare (con, query, 0, &cci_error);
...
ret = cci_get_query_plan(req, &out_buf);
...
printf("plan = %s", out_buf);
cci_query_info_free(out_buf);

Releases the result buffer memory allocated from the cci_get_query_plan() function.

The cci_get_query_timeout function returns timeout configured for query execution.

If the prepared statement is SELECT, the T_CCI_COL_INFO struct that stores the column information about the execution result can be obtained by using this function. If it is not SELECT, NULL is returned and the num value becomes 0.

You can access the T_CCI_COL_INFO struct directly to get the column information from the struct, but you can also use a macro to get the information, which is defined as follows. The address of the T_CCI_COL_INFO struct and the column index are specified as parameters for each macro. The macro can be called only for the SELECT query. Note that the validity check is not performed for each parameter entered in each macro. If the return type of the macro is char*, do not free the memory pointer.

col_info = cci_get_result_info (req, &stmt_type, &col_count);
if (col_info == NULL)
{
  printf ("get_result_info error\n");
  goto handle_error;
}

for (i = 1; i <= col_count; i++)
{
  printf ("%-12s = %d\n", "type", CCI_GET_RESULT_INFO_TYPE (col_info, i));
  printf ("%-12s = %d\n", "scale",
          CCI_GET_RESULT_INFO_SCALE (col_info, i));
  printf ("%-12s = %d\n", "precision",
          CCI_GET_RESULT_INFO_PRECISION (col_info, i));
  printf ("%-12s = %s\n", "name", CCI_GET_RESULT_INFO_NAME (col_info, i));
  printf ("%-12s = %s\n", "attr_name",
          CCI_GET_RESULT_INFO_ATTR_NAME (col_info, i));
  printf ("%-12s = %s\n", "class_name",
          CCI_GET_RESULT_INFO_CLASS_NAME (col_info, i));
  printf ("%-12s = %s\n", "is_non_null",
          CCI_GET_RESULT_INFO_IS_NON_NULL (col_info,i) ? "true" : "false");
}

The cci_get_version function gets the version of CCI library. In case of version "9.2.0.0001", 9 is the major version, 2 is the minor version, and 0 is the patch version.

$ strings /home/usr1/CUBRID/lib/libcascci.so | grep VERSION
VERSION=9.2.0.0001

If you compile the CCI application program for Windows with static linking library(.lib), this function should be called always. In the other cases, this does not need to be called.

The cci_is_holdable function returns whether the request handle(req_handle) is holdable or not.

The cci_is_updatable function checks the SQL statement executing cci_prepare() can make updatable result set (which means CCI_PREPARE_UPDATABLE is configured in flag when executing cci_prepare()).

The cci_next_result function gets results of next query if CCI_EXEC_QUERY_ALL flag is set upon cci_execute(). The information about the query fetched by next_result can be obtained with cci_get_result_info(). If next_result is executed successfully, the database is updated with the information of the current query.

You can execute multiple queries in the written order when CCI_EXEC_QUERY_ALL flag is set on cci_execute(). At this time, CUBRID brings the first query's result after calling cci_execute(); CUBRID brings the second and the other queries' results after calling cci_next_result function. At this time, the column information about the query result can be brought by calling cci_get_result_info() function whenever cci_execute() function or cci_next_result function is called.

In other words, when you run Q1, Q2, and Q3 at once with calling cci_prepare() function, the result of Q1 is brought by calling cci_execute(); the result of Q2 or Q3 is brought by calling cci_next_result. The result of Q1, Q2 or Q3 is brought by calling cci_get_result_info() function for each time.

sql = "SELECT * FROM athlete; SELECT * FROM nation; SELECT * FROM game";
req = cci_prepare (con, sql, 0, &error);
...
ret = cci_execute (req, CCI_EXEC_QUERY_ALL, 0, &error);
res_col_info = cci_get_result_info (req, &cmd_type, &col_count);
...
ret = cci_next_result (req, &error);
res_col_info = cci_get_result_info (req, &cmd_type, &col_count);
...
ret = cci_next_result (req, &error);
res_col_info = cci_get_result_info (req, &cmd_type, &col_count);

The error code CAS_ER_NO_MORE_RESULT_SET means that no more result set exists.

By the value of cmd argument, it executes the following behavior.

• CCI_OID_DROP: Deletes the given oid.
• CCI_OID_IS_INSTANCE: Checks whether the given oid is an instance oid.
• CCI_OID_LOCK_READ: Sets read lock on the given oid.
• CCI_OID_LOCK_WRITE: Sets write lock on the given oid.

The cci_oid_get function gets the attribute values of the given oid. attr_name is an array of the attributes, and it must end with NULL. If attr_name is NULL, the information of all attributes is fetched. The request handle has the same form as when the SQL statement "SELECT attr_name FROM oid_class WHERE oid_class = oid" is executed.

The cci_oid_get_class_name function gets the class name of the given oid.

The cci_oid_put function configures the attr_name attribute values of the given oid to new_val_str. The last value of attr_name must be NULL. Any value of any type must be represented as a string. The value represented as a string is applied to the database after being converted depending on the attribute type on the server. To insert a NULL value, configure the value of new_val_str [i] to NULL.

The cci_oid_put2 function sets the attr_name attribute values of the given oid to new_val. The last value of attr_name must be NULL. To insert a NULL value, set the value of new_val [i] to NULL.

The type of new_val [i] for a_type is shown in the table below.

Type of new_val[i] for a_type

char *attr_name[array_size]
void *attr_val[array_size]
int a_type[array_size]
int int_val

...

attr_name[0] = "attr_name0"
attr_val[0] = &int_val
a_type[0] = CCI_A_TYPE_INT
attr_name[1] = "attr_name1"
attr_val[1] = "attr_val1"
a_type[1] = CCI_A_TYPE_STR

...
attr_name[num_attr] = NULL

res = cci_put2(con_h, oid_str, attr_name, attr_val, a_type, &error)

The cci_prepare() function prepares SQL execution by acquiring request handle for SQL statements. If a SQL statement consists of multiple queries, the preparation is performed only for the first query. With the parameter of this function, an address to T_CCI_ERROR where connection handle, SQL statement, flag, and error information are stored.

CCI_PREPARE_UPDATABLE, CCI_PREPARE_INCLUDE_OID, CCI_PREPARE_CALL or CCI_PREPARE_HOLDABLE can be configured in flag. If CCI_PREPARE_UPDATABLE is configured, updatable resultset is created and CCI_PREPARE_INCLUDE_OID is automatically configured. CCI_PREPARE_UPDATABLE and CCI_PREPARE_HOLDABLE cannot be used simultaneously in flag. If you want to call the Java Stored Procedure, specify CCI_PREPARE_CALL flag into the cci_prepare function. You can see an related example on cci_register_out_param().

The default value of whether to keep result set after commit is cursor holdability. Thus, if you want to configure CCI_PREPARE_UPDATABLE in flag of cci_prepare(), you should call cci_set_holdability() first before calling cci_prepare() so that cursor cannot be maintained.

However, not all updatable resultsets are created even though CCI_PREPARE_UPDATABLE is configured. So you need to check if the results are updatable by using cci_is_updatable() after preparation. You can use cci_oid_put() or cci_oid_put2() to update result sets.

The conditions of updatable queries are as follows:

• Must be SELECT.
• OID can be included in the query result.
• The column to be updated must be the one that belongs to the table specified in the FROM clause.

If CCI_PREPARE_HOLDABLE is set, a cursor is held as long as result set is closed or connection is disconnected after the statement is committed(see Cursor Holdability).

The cci_prepare_and_execute function executes the SQL statement immediately and returns a request handle for the SQL statement. A request handle, SQL statement, the maximum length of a column to be fetched, error code, and the address of a T_CCI_ERROR construct variable in which error information being stored are specified as arguments. max_col_size is a value to configure the maximum length of a column to be sent to a client when the column of a SQL statement is CHAR, VARCHAR, BIT, or VARBIT. If this value is 0, full length is fetched.

The cci_property_create function creates T_CCI_PROPERTIES struct to configure DATASOURCE of CCI.

The cci_property_destroy function destroys T_CCI_PROPERTIES struct.

The cci_property_get function retrieves the property value configured in the T_CCI_PROPERTIES struct.